Usenet 1993 July/InfoMagic USENET CD-ROM July 1993.ISO/sources/misc/volume24/gnucalc/part53

Text File | 1991-11-02 | 55.4 KB | 1,344 lines

Newsgroups: comp.sources.misc
From: [e-mail] (David Gillespie)
Subject:  v24i101:  gnucalc - GNU Emacs Calculator, v2.00, Part53/56
Message-ID: <[e-mail]>
X-Md4-Signature: 42d6fbdd570052add95bd12c0e6a560c
Date: Sun, 3 Nov 1991 00:11:21 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (David Gillespie)
Posting-number: Volume 24, Issue 101
Archive-name: gnucalc/part53
Environment: Emacs
Supersedes: gmcalc: Volume 13, Issue 27-45

#!/bin/sh
# do not concatenate these parts, unpack them in order with /bin/sh
# file calc.texinfo continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 53; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
    echo 'x - still skipping calc.texinfo'
else
echo 'x - continuing file calc.texinfo'
sed 's/^X//' << 'SHAR_EOF' >> 'calc.texinfo' &&
@samp{(calc-eval "1+2,3+4" ";")} returns @samp{"3;7"}.
X
The ``separator'' can also be any of several Lisp symbols which
request other behaviors from @code{calc-eval}.  These are discussed
one by one below.
X
You can give additional arguments to be substituted for
@samp{$}, @samp{$$}, and so on in the main expression.  For
example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the
expression @samp{"7/(1+1)"} to yield the result @samp{"3.5"}
(assuming Fraction mode is not in effect).  Note the @code{nil}
used as a placeholder for the item-separator argument.
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Numbers Only
X
@noindent
Sometimes it is preferable to treat @samp{1 / 0} as an error
rather than returning a symbolic result.  If you pass the symbol
@code{num} as the second argument to @code{calc-eval}, results
that are not constants are treated as errors.  The error message
reported is the first @samp{calc-why} message if there is one,
or otherwise ``Number expected.''
X
A result is ``constant'' if it is a number, vector, or other
object that does not include variables or function calls.  If it
is a vector, the components must themselves be constants.
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Error Handling
X
@noindent
If @code{calc-eval} encounters an error, it returns a list containing
the character position of the error, plus a suitable message as a
string.  Note that @samp{1 / 0} is @emph{not} an error by Calc's
standards; it simply returns the string @samp{"1 / 0"} which is the
division left in symbolic form.  But @samp{(calc-eval "1/")} will
return the list @samp{(2 "Expected a number")}.
X
If you bind the variable @code{calc-eval-error} to @code{t}
using a @code{let} form surrounding the call to @code{calc-eval},
errors instead call the Emacs @code{error} function which aborts
to the Emacs command loop with a beep and an error message.
X
If you bind this variable to the symbol @code{string}, error messages
are returned as strings instead of lists.  The character position is
ignored.
X
As a courtesy to other Lisp code which may be using Calc, be sure
to bind @code{calc-eval-error} using @code{let} rather than changing
it permanently with @code{setq}.
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Default Modes
X
@noindent
If the first argument to @code{calc-eval} is a list whose first
element is a formula string, then @code{calc-eval} sets all the
various Calc modes to their default values while the formula is
evaluated and formatted.  For example, the precision is set to 12
digits, digit grouping is turned off, and the normal language
mode is used.
X
This same principle applies to the other options discussed below.
If the first argument would normally be @var{x}, then it can also
be the list @samp{(@var{x})} to use the default mode settings.
X
If there are other elements in the list, they are taken as
variable-name/value pairs which override the default mode
settings.  Look at the documentation at the front of the
@file{calc.el} file to find the names of the Lisp variables for
the various modes.  The mode settings are restored to their
original values when @code{calc-eval} is done.
X
For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)}
computes the sum of two numbers, requiring a numeric result, and
using default mode settings except that the precision is 8 instead
of the default of 12.
X
It's usually best to use this form of @code{calc-eval} unless your
program actually considers the interaction with Calc's mode settings
to be a feature.  This will avoid all sorts of potential ``gotchas'';
consider what happens with @samp{(calc-eval "sqrt(2)" 'num)}
when the user has left Calc in symbolic mode or no-simplify mode.
X
As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")}
checks if the number in string @cite{a} is less than the one in
string @cite{b}.  Without using a list, the integer 1 might
come out in a variety of formats which would be hard to test for
conveniently: @samp{"1"}, @samp{"8#1"}, @samp{"00001"}.  (But
see ``Predicates'' mode, below.)
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Raw Numbers
X
@noindent
Normally all input and output for @code{calc-eval} is done with strings.
You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)}
in place of @samp{(+ a b)}, but this is very inefficient since the
numbers must be converted to and from string format as they are passed
from one @code{calc-eval} to the next.
X
If the separator is the symbol @code{raw}, the result will be returned
as a raw Calc data structure rather than a string.  You can read about
how these objects look in the following sections, but usually you can
treat them as ``black box'' objects with no important internal
structure.
X
There is also a @code{rawnum} symbol, which is a combination of
@code{raw} (returning a raw Calc object) and @code{num} (signalling
an error if that object is not a constant).
X
You can pass a raw Calc object to @code{calc-eval} in place of a
string, either as the formula itself or as one of the @samp{$}
arguments.  Thus @samp{(calc-eval "$+$$" 'raw a b)} is an
addition function that operates on raw Calc objects.  Of course
in this case it would be easier to call the low-level @code{math-add}
function in Calc, if you can remember its name.
X
In particular, note that a plain Lisp integer is acceptable to Calc
as a raw object.  (All Lisp integers are accepted on input, but
integers of more than six decimal digits are converted to ``big-integer''
form for output.  @xref{Data Type Formats}.)
X
When it comes time to display the object, just use @samp{(calc-eval a)}
to format it as a string.
X
It is an error if the input expression evaluates to a list of
values.  The separator symbol @code{list} is like @code{raw}
except that it returns a list of one or more raw Calc objects.
X
Note that a Lisp string is not a valid Calc object, nor is a list
containing a string.  Thus you can still safely distinguish all the
various kinds of error returns discussed above.
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Predicates
X
@noindent
If the separator symbol is @code{pred}, the result of the formula is
treated as a true/false value; @code{calc-eval} returns @code{t} or
@code{nil}, respectively.  A value is considered ``true'' if it is a
non-zero number, or false if it is zero or if it is not a number.
X
For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether
one value is less than another.
X
As usual, it is also possible for @code{calc-eval} to return one of
the error indicators described above.  Lisp will interpret such an
indicator as ``true'' if you don't check for it explicitly.  If you
wish to have an error register as ``false'', use something like
@samp{(eq (calc-eval ...) t)}.
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Variable Values
X
@noindent
Variables in the formula passed to @code{calc-eval} are not normally
replaced by their values.  If you wish this, you can use the
@code{evalv} function (@pxref{Algebraic Manipulation}).  For example,
if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable
@code{var-a}), then @samp{(calc-eval "a+pi")} will return the
formula @samp{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")}
will return @samp{"7.14159265359"}.
X
To store in a Calc variable, just use @code{setq} to store in the
corresponding Lisp variable.  (This is obtained by prepending
@samp{var-} to the Calc variable name.)  Calc routines will
understand either string or raw form values stored in variables,
although raw data objects are much more efficient.  For example,
to increment the Calc variable @code{a}:
X
@example
(setq var-a (calc-eval "evalv(a+1)" 'raw))
@end example
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Stack Access
X
@noindent
If the separator symbol is @code{push}, the formula argument is
evaluated (with possible @samp{$} expansions, as usual).  The
result is pushed onto the Calc stack.  The return value is @code{nil}
(unless there is an error from evaluating the formula).
X
If the separator symbol is @code{pop}, the first argument to
@code{calc-eval} must be an integer instead of a string.  That
many values are popped from the stack and thrown away.  A negative
argument deletes the entry at that stack level.  The return value
is the number of elements remaining in the stack after popping;
@samp{(calc-eval 0 'pop)} is a good way to measure the size of
the stack.
X
If the separator symbol is @code{top}, the first argument to
@code{calc-eval} must again be an integer.  The value at that
stack level is formatted as a string and returned.  Thus
@samp{(calc-eval 1 'top)} returns the top-of-stack value.  If the
integer is out of range, @code{nil} is returned.
X
The separator symbol @code{rawtop} is just like @code{top} except
that the stack entry is returned as a raw Calc object instead of
as a string.
X
In all of these cases the first argument can be made a list in
order to force the default mode settings, as described above.
Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the
second-to-top stack entry, formatted as a string using the default
instead of current display modes, except that the radix is
hexadecimal instead of decimal.
X
It is, of course, polite to put the Calc stack back the way you
found it when you are done, unless the user of your program is
actually expecting it to affect the stack.
X
Note that you do not actually have to switch into the @samp{*Calculator*}
buffer in order to use @code{calc-eval}; it temporarily switches into
the stack buffer if necessary.
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Keyboard Macros
X
@noindent
If the separator symbol is @code{macro}, the first argument must be a
string of characters which Calc can execute as a sequence of keystrokes.
This switches into the Calc buffer for the duration of the macro.
For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the
vector @samp{[1,2,3,4,5]} on the stack and then replaces it
with the sum of those numbers.  Note that @samp{\r} is the Lisp
notation for the carriage-return, @key{RET}, character.
X
If your keyboard macro wishes to pop the stack, @samp{\C-d} is
safer than @samp{\177} (the @key{DEL} character) because some
installations may have switched the meanings of @key{DEL} and
@kbd{C-h}.  Calc always interprets @kbd{C-d} as a synonym for
``pop-stack'' regardless of key mapping.
X
If you provide a third argument to @code{calc-eval}, evaluation
of the keyboard macro will leave a record in the Trail using
that argument as a tag string.  Normally the Trail is unaffected.
X
The return value in this case is always @code{nil}.
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Lisp Evaluation
X
@noindent
Finally, if the separator symbol is @code{eval}, then the Lisp
@code{eval} function is called on the first argument, which must
be a Lisp expression rather than a Calc formula.  Remember to
quote the expression so that it is not evaluated until inside
@code{calc-eval}.
X
The difference from plain @code{eval} is that @code{calc-eval}
switches to the Calc buffer before evaluating the expression.
For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)}
will correctly affect the buffer-local Calc precision variable.
X
An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}.
This is evaluating a call to the function that is normally invoked
by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.''
Note that this function will leave a message in the echo area as
a side effect.  Also, all Calc functions switch to the Calc buffer
automatically if not invoked from there, so the above call is
also equivalent to @samp{(calc-precision 17)} by itself.
In all cases, Calc uses @code{save-excursion} to switch back to
your original buffer when it is done.
X
As usual the first argument can be a list that begins with a Lisp
expression to use default instead of current mode settings.
X
The result of @code{calc-eval} in this usage is just the result
returned by the evaluated Lisp expression.
X
@ifinfo
@example
X
@end example
@end ifinfo
@subsubsection Example
X
@noindent
@findex convert-temp
Here is a sample Emacs command that uses @code{calc-eval}.  Suppose
you have a document with lots of references to temperatures on the
Fahrenheit scale, say ``98.6 F'', and you wish to convert these
references to Centigrade.  The following command does this conversion.
Place the Emacs cursor right after the letter ``F'' and invoke the
command to change ``98.6 F'' to ``37 C''.  Or, if the temperature is
already in Centigrade form, the command changes it back to Fahrenheit.
X
@example
(defun convert-temp ()
X  (interactive)
X  (save-excursion
X    (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)")
X    (let* ((top1 (match-beginning 1))
X           (bot1 (match-end 1))
X           (number (buffer-substring top1 bot1))
X           (top2 (match-beginning 2))
X           (bot2 (match-end 2))
X           (type (buffer-substring top2 bot2)))
X      (if (equal type "F")
X          (setq type "C"
X                number (calc-eval "($ - 32)*5/9" nil number))
X        (setq type "F"
X              number (calc-eval "$*9/5 + 32" nil number)))
X      (goto-char top2)
X      (delete-region top2 bot2)
X      (insert-before-markers type)
X      (goto-char top1)
X      (delete-region top1 bot1)
X      (if (string-match "\\.$" number)   ; change "37." to "37"
X          (setq number (substring number 0 -1)))
X      (insert number))))
@end example
X
Note the use of @code{insert-before-markers} when changing between
``F'' and ``C'', so that the character winds up before the cursor
instead of after it.
X
@node Internals, , Calling Calc from Your Programs, Lisp Definitions
@subsection Calculator Internals
X
@noindent
This section describes the Lisp functions defined by the Calculator that
may be of use to user-written Calculator programs (as described in the
rest of this chapter).  These functions are shown by their names as they
conventionally appear in @code{defmath}.  Their full Lisp names are
generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their
apparent names.  (Names that begin with @samp{calc-} are already in
their full Lisp form.)  You can use the actual full names instead if you
prefer them, or if you are calling these functions from regular Lisp.
X
Little distinction is made here between functions in the main Calc body
and functions in the extensions module (@file{calc-ext.el}).  Because
@code{defmath} itself uses the extensions, user-written code generally
always executes with the extensions already loaded, so this is not an
issue.  If you are doing something special, check carefully to make sure
each function you are using is from the main body, and call
@samp{(calc-extensions)} before using any function from the extensions
package if you can't prove the extensions will already have been loaded.
X
@menu
* Data Type Formats::
* Interactive Lisp Functions::
* Stack Lisp Functions::
* Predicates::
* Computational Lisp Functions::
* Vector Lisp Functions::
* Symbolic Lisp Functions::
* Formatting Lisp Functions::
* Lisp Variables::
* Hooks::
@end menu
X
@node Data Type Formats, Interactive Lisp Functions, Internals, Internals
@subsubsection Data Type Formats
X
@noindent
Integers are stored in either of two ways, depending on their magnitude.
Integers less than one million in absolute value are stored as standard
Lisp integers.  This is the only storage format for Calc data objects
which is not a Lisp list.
X
Large integers are stored as a list of the form @samp{(bigpos @var{d0}
@var{d1} @var{d2} @dots{})} for positive integers 1000000 or more, or
@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative integers
-1000000 or less.  Each @var{d} is a base-1000 ``digit,'' a Lisp integer
from 0 to 999.  The least significant digit is @var{d0}; the last digit,
@var{dn}, which is always nonzero, is the most significant digit.  For
example, the integer @i{-12345678} is stored as @samp{(bigneg 678 345 12)}.
X
The distinction between small and large integers is entirely hidden from
the user.  In @code{defmath} definitions, the Lisp predicate @code{integerp}
returns true for either kind of integer, and in general both big and small
integers are accepted anywhere the word ``integer'' is used in this manual.
If the distinction must be made, native Lisp integers are called @dfn{fixnums}
and large integers are called @dfn{bignums}.
X
Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})}
where @var{n} is an integer (big or small) numerator, @var{d} is an
integer denominator greater than one, and @var{n} and @var{d} are relatively
prime.  Note that fractions where @var{d} is one are automatically converted
to plain integers by all math routines; fractions where @var{d} is negative
are normalized by negating the numerator and denominator.
X
Floating-point numbers are stored in the form, @samp{(float @var{mant}
@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than
@samp{10^@var{p}} in absolute value (@var{p} represents the current
precision), and @var{exp} (the ``exponent'') is a fixnum.  The value of
the float is @samp{@var{mant} * 10^@var{exp}}.  For example, the number
-3.14 is stored as @samp{(float -314 -2) = -314*10^-2}.  Other constraints
are that the number 0.0 is always stored as @samp{(float 0 0)}, and,
except for the 0.0 case, the rightmost base-10 digit of @var{mant} is
always nonzero.  (If the rightmost digit is zero, the number is
rearranged by dividing @var{mant} by ten and incrementing @var{exp}.)@refill
X
Rectangular complex numbers are stored in the form @samp{(cplx @var{re}
@var{im})}, where @var{re} and @var{im} are each real numbers, either
integers, fractions, or floats.  The value is @samp{@var{re} + @var{im}i}.
The @var{im} part is nonzero; complex numbers with zero imaginary
components are converted to real numbers automatically.@refill
X
Polar complex numbers are stored in the form @samp{(polar @var{r}
@var{theta})}, where @var{r} is a positive real value and @var{theta}
is a real value or HMS form representing an angle.  This angle is
usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees,
or @samp{(-pi ..@: pi)} radians, according to the current angular mode.
If the angle is 0 the value is converted to a real number automatically.
(If the angle is 180 degrees, the value is usually also converted to a
negative real number.)@refill
X
Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m}
@var{s})}, where @var{h} is an integer or an integer-valued float (i.e.,
a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued
float in the range @samp{[0 ..@: 60)}, and @var{s} is any real number in the
range @samp{[0 ..@: 60)}.@refill
X
Date forms are stored as @samp{(date @var{n})}, where @var{n} is
a real number that counts days since midnight on the morning of
January 1, 1 AD.  If @var{n} is an integer, this is a pure date
form.  If @var{n} is a fraction or float, this is a date/time form.
X
Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a
positive real number or HMS form, and @var{n} is a real number or HMS
form in the range @samp{[0 ..@: @var{m})}.
X
Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x}
is the mean value and @var{sigma} is the standard deviation.  Each
component is either a number, an HMS form, or a symbolic object
(a variable or function call).  If @var{sigma} is zero, the value is
converted to a plain real number.  If @var{sigma} is negative or
complex, it is automatically normalized to be a positive real.
X
Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})},
where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and
@var{hi} are real numbers, HMS forms, or symbolic objects.  The @var{mask}
is a binary integer where 1 represents the fact that the interval is
closed on the high end, and 2 represents the fact that it is closed on
the low end.  (Thus 3 represents a fully closed interval.)  The interval
@samp{(intv 3 @var{x} @var{x})} is converted to the plain number @var{x};
intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask}
represent empty intervals.  If @var{hi} is less than @var{lo}, the interval
is converted to a standard empty interval by replacing @var{hi} with @var{lo}.
X
Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1}
is the first element of the vector, @var{v2} is the second, and so on.
An empty vector is stored as @samp{(vec)}.  A matrix is simply a vector
where all @var{v}'s are themselves vectors of equal lengths.
X
Variables are stored as @samp{(var @var{name} @var{sym})}, where
@var{name} is a Lisp symbol whose print name is used as the visible name
of the variable, and @var{sym} is a Lisp symbol in which the variable's
value is actually stored.  Thus, @samp{(var pi var-pi)} represents the
special constant @samp{pi}.  Almost always, the form is @samp{(var
@var{v} var-@var{v})}.  If the variable name was entered with @code{#}
signs (which are converted to hyphens internally), the form is
@samp{(var @var{v} @var{v})}.  The value of a variable is the Calc
object stored in its @var{sym} symbol's value cell.  If the symbol's
value cell is void or if it contains @code{nil}, the variable has no
value.  Special constants have the form @samp{(special-const
@var{value})} stored in their value cell, where @var{value} is a formula
which is evaluated when the constant's value is requested.  Variables
which represent units are not stored in any special way; they are units
only because their names appear in the units table.  If the value
cell contains a string, it is parsed to get the variable's value when
the variable is used.@refill
X
A Lisp list with any other symbol as the first element is a function call.
The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^},
and @code{|} represent special binary operators; these lists are always
of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the
sub-formula on the lefthand side and @var{rhs} is the sub-formula on the
right.  The symbol @code{neg} represents unary negation; this list is always
of the form @samp{(neg @var{arg})}.  Any other symbol @var{func} represents a
function that would be displayed in function-call notation; the symbol
@var{func} is in general always of the form @samp{calcFunc-@var{name}}.
The function cell of the symbol @var{func} should contain a Lisp function
for evaluating a call to @var{func}.  This function is passed the remaining
elements of the list (themselves already evaluated) as arguments; such
functions should return @code{nil} or call @code{reject-arg} to signify
that they should be left in symbolic form, or they should return a Calc
object which represents their value, or a list of such objects if they
wish to return multiple values.  (The latter case is allowed only for
functions which are the outer-level call in an expression whose value is
about to be pushed on the stack.)@refill
X
@node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals
@subsubsection Interactive Functions
X
@noindent
The functions described here are used in implementing interactive Calc
commands.
X
@defun calc-set-command-flag flag
Set the command flag @var{flag}.  This is generally a Lisp symbol, but
may in fact by anything.  The effect is to add @var{flag} to the list
stored in the variable @code{calc-command-flags}, unless it is already
there.  @xref{Defining Simple Commands}.
@end defun
X
@defun calc-clear-command-flag flag
If @var{flag} appears among the list of currently-set command flags,
remove it from that list.
@end defun
X
@defun calc-record-undo rec
Add the ``undo record'' @var{rec} to the list of steps to take if the
current operation should need to be undone.  Stack push and pop functions
automatically call @code{calc-record-undo}, so the kinds of undo records
you might need to create take the form @samp{(set @var{sym} @var{value})},
which says that the Lisp variable @var{sym} was changed and had previously
contained @var{value}; @samp{(store @var{var} @var{value})} which says that
the Calc variable @var{var} (a string which is the name of the symbol that
contains the variable's value) was stored and its previous value was
@var{value} (either a Calc data object, or @var{nil} if the variable was
previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})},
which means that to undo requires calling the function @samp{(@var{undo}
@var{args} @dots{})} and, if the undo is later redone, calling
@samp{(@var{redo} @var{args} @dots{})}.@refill
@end defun
X
@defun calc-record-why msg args
Record the error or warning message @var{msg}, which is normally a string.
This message will be replayed if the user types @kbd{w} (@code{calc-why});
the first such message recorded for a command will be replayed automatically
if the user has turned on @code{calc-auto-why} mode.  If one or more
@var{args} are present, the displayed message will be of the form,
@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are
formatted on the assumption that they are either strings or Calc objects of
some sort.  If @var{msg} is a symbol, it is the name of a Calc predicate
(such as @code{integerp} or @code{numvecp}) which the arguments did not
satisfy; it is expanded to a suitable string such as ``Expected an
integer.''  The @code{reject-arg} function calls @code{calc-record-why}
automatically; @pxref{Predicates}.@refill
@end defun
X
@defun calc-is-inverse
This predicate returns true if the current command is inverse,
i.e., if the Inverse (@kbd{I} key) flag was set.
@end defun
X
@defun calc-is-hyperbolic
This predicate is the analogous function for the @kbd{H} key.
@end defun
X
@node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals
@subsubsection Stack-Oriented Functions
X
@noindent
The functions described here perform various operations on the Calc
stack and trail.  They are to be used in interactive Calc commands.
X
@defun calc-push-list vals n
Push the Calc objects in list @var{vals} onto the stack at stack level
@var{n}.  If @var{n} is omitted it defaults to 1, so that the elements
are pushed at the top of the stack.  If @var{n} is greater than 1, the
elements will be inserted into the stack so that the last element will
end up at level @var{n}, the next-to-last at level @var{n}+1, etc.
The elements of @var{vals} are assumed to be valid Calc objects, and
are not evaluated or renormalized in any way.  If @var{vals} is an
empty list, nothing happens.@refill
X
The stack elements are pushed without any sub-formula selections.
You can give an optional third argument to this function, which must
be a list the same size as @var{vals} of selections.  Each selection
must be @code{eq} to some sub-formula of the corresponding formula
in @var{vals}, or @code{nil} if that formula should have no selection.
@end defun
X
@defun calc-top-list n m
Return a list of the @var{n} objects starting at level @var{m} of the
stack.  If @var{m} is omitted it defaults to 1, so that the elements are
taken from the top of the stack.  If @var{n} is omitted, it also
defaults to 1, so that the top stack element (in the form of a
one-element list) is returned.  If @var{m} is greater than 1, the
@var{m}th stack element will be at the end of the list, the @var{m}+1st
element will be next-to-last, etc.  If @var{n} or @var{m} are out of
range, the command is aborted with a suitable error message.  If @var{n}
is zero, the function returns an empty list.  The stack elements are not
evaluated or renormalized.@refill
X
If any stack elements contain selections, and selections have not
been disabled by the @kbd{j e} (@code{calc-enable-selections}) command,
this function returns the selection portions rather than the entire
stack elements.  It can be given a third ``selection-mode'' argument
which selection other behaviors.  If it is the symbol @code{t}, then
a selection in any of the requested stack elements produces an
``illegal operation on selections'' error.  If it the symbol @code{full},
the whole stack entry is always returned regardless of selections.
If is the symbol @code{sel}, the selected portion is always returned,
or @code{nil} if there is no selection.  (This mode ignores the @kbd{j e}
command.)  If the symbol is @code{entry}, the complete stack entry in
list form is returned; the first element of this list will be the whole
formula, and the third element will be the selection (or @code{nil}).
@end defun
X
@defun calc-pop-stack n m
Remove the specified elements from the stack.  The parameters @var{n}
and @var{m} are defined the same as for @code{calc-top-list}.  The return
value of @code{calc-pop-stack} is uninteresting.
X
If there are any selected sub-formulas among the popped elements, and
@kbd{j e} has not been used to disable selections, this produces an
error without changing the stack.  If you supply an optional third
argument of @code{t}, the stack elements are popped even if they
contain selections.
@end defun
X
@defun calc-record-list vals tag
This function records one or more results in the trail.  The @var{vals}
are a list of strings or Calc objects.  The @var{tag} is the four-character
tag string to identify the values.  If @var{tag} is omitted, a blank tag
will be used.
@end defun
X
@defun calc-normalize n
This function takes a Calc object and ``normalizes'' it.  At the very
least this involves re-rounding floating-point values according to the
current precision and other similar jobs.  Also, unless the user has
selected no-simplify mode (@pxref{Simplification Modes}), this involves
actually evaluating a formula object by executing the function calls
it contains.
@end defun
X
@defun calc-top-list-n n m
This function is identical to @code{calc-top-list}, except that it calls
@code{calc-normalize} on the values that it takes from the stack.  They
are also passed through @code{check-complete}, so that incomplete
objects will be rejected with an error message.  All computational
commands should use this in preference to @code{calc-top-list}; the only
standard Calc commands that operate on the stack without normalizing
are stack management commands like @code{calc-enter} and @code{calc-roll-up}.
This function accepts the same optional selection-mode argument as
@code{calc-top-list}.
@end defun
X
@defun calc-top-n m
This function is a convenient form of @code{calc-top-list-n} in which only
a single element of the stack is taken and returned, rather than a list
of elements.  This also accepts an optional selection-mode argument.
@end defun
X
@defun calc-enter-result n tag vals
This function is a convenient interface to most of the above functions.
The @var{vals} argument should be either a single Calc object, or a list
of Calc objects; the object or objects are normalized, and the top @var{n}
stack entries are replaced by the normalized objects.  If @var{tag} is
non-@code{nil}, the normalized objects are also recorded in the trail.
A typical stack-based computational command would take the form,
X
@smallexample
(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func}
X                               (calc-top-list-n @var{n})))
@end smallexample
X
If any of the @var{n} stack elements replaced contain sub-formula
selections, and selections have not been disabled by @kbd{j e},
this function takes one of two courses of action.  If @var{n} is
equal to the number of elements in @var{vals}, then each element of
@var{vals} is spliced into the corresponding selection; this is what
happens when you use the @key{TAB} key, or when you use a unary
arithmetic operation like @code{sqrt}.  If @var{vals} has only one
element but @var{n} is greater than one, there must be only one
selection among the top @var{n} stack elements; the element from
@var{vals} is spliced into that selection.  This is what happens when
you use a binary arithmetic operation like @kbd{+}.  Any other
combination of @var{n} and @var{vals} when selections are present
is an error.
@end defun
X
@defun calc-unary-op tag func arg
This function implements a unary operator that allows a numeric prefix
argument to apply the operator over many stack entries.  If the prefix
argument @var{arg} is @code{nil}, this uses @code{calc-enter-result}
as outlined above.  Otherwise, it maps the function over several stack
elements; @pxref{Prefix Arguments}.  For example,@refill
X
@smallexample
(defun calc-zeta (arg)
X  (interactive "P")
X  (calc-unary-op "zeta" 'calcFunc-zeta arg))
@end smallexample
@end defun
X
@defun calc-binary-op tag func arg ident unary
This function implements a binary operator, analogously to
@code{calc-unary-op}.  The optional @var{ident} and @var{unary}
arguments specify the behavior when the prefix argument is zero or
one, respectively.  If the argument is zero, the value @var{ident}
is pushed onto the stack, if specified, otherwise an error message
is displayed.  If the argument is one, the unary function @var{unary}
is applied to the top stack element, or, if @var{unary} is not
specified, nothing happens.  When the argument is two or more,
the binary function @var{func} is reduced across the top @var{arg}
stack elements; when the argument is negative, the function is
mapped between the next-to-top -@var{arg} stack elements and the
top element.@refill
@end defun
X
@defun calc-stack-size
Return the number of elements on the stack as an integer.  This count
does not include elements that have been temporarily hidden by stack
truncation; @pxref{Truncating the Stack}.
@end defun
X
@defun calc-cursor-stack-index n
Move the point to the @var{n}th stack entry.  If @var{n} is zero, this
will be the @samp{.} line.  If @var{n} is from 1 to the current stack size,
this will be the beginning of the first line of that stack entry's display.
If line numbers are enabled, this will move to the first character of the
line number, not the stack entry itself.@refill
@end defun
X
@defun calc-substack-height n
Return the number of lines between the beginning of the @var{n}th stack
entry and the bottom of the buffer.  If @var{n} is zero, this
will be one (assuming no stack truncation).  If all stack entries are
one line long (i.e., no matrices are displayed), the return value will
be equal @var{n}+1 as long as @var{n} is in range.@refill
@end defun
X
@defun calc-refresh
Erase the @code{*Calculator*} buffer and reformat its contents from memory.
This must be called after changing any parameter, such as the current
display radix, which might change the appearance of existing stack
entries.  (During a keyboard macro invoked by the @kbd{X} key, refreshing
is suppressed, but a flag is set so that the entire stack will be refreshed
rather than just the top few elements when the macro finishes.)@refill
@end defun
X
@node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals
@subsubsection Predicates
X
@noindent
The functions described here are predicates, that is, they return a
true/false value where @code{nil} means false and anything else means
true.  These predicates are expanded by @code{defmath}, for example,
from @code{zerop} to @code{math-zerop}.  In many cases they correspond
to native Lisp functions by the same name, but are extended to cover
the full range of Calc data types.
X
@defun zerop x
Returns true if @var{x} is numerically zero, in any of the Calc data
types.  (Note that for some types, such as error forms and intervals,
it never makes sense to return true.)  In @code{defmath}, the expression
@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)},
and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}.
@end defun
X
@defun negp x
Returns true if @var{x} is negative.  This accepts negative real numbers
of various types, negative HMS and date forms, and intervals in which
all included values are negative.  In @code{defmath}, the expression
@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)},
and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}.
@end defun
X
@defun posp x
Returns true if @var{x} is positive (and non-zero).
@end defun
X
@defun looks-negp x
Returns true if @var{x} is ``negative-looking.''  This returns true if
@var{x} is a negative number, or a formula with a leading minus sign
such as @samp{-a/b}.  In other words, this is an object which can be
made simpler by calling @code{(- @var{x})}.
@end defun
X
@defun integerp x
Returns true if @var{x} is an integer of any size.
@end defun
X
@defun fixnump x
Returns true if @var{x} is a native Lisp integer.
@end defun
X
@defun natnump x
Returns true if @var{x} is a nonnegative integer of any size.
@end defun
X
@defun fixnatnump x
Returns true if @var{x} is a nonnegative Lisp integer.
@end defun
X
@defun num-integerp x
Returns true if @var{x} is numerically an integer, i.e., either a
true integer or a float with no significant digits to the right of
the decimal point.
@end defun
X
@defun messy-integerp x
Returns true if @var{x} is numerically, but not literally, an integer.
A value is @code{num-integerp} if it is @code{integerp} or
@code{messy-integerp} (but it is never both at once).
@end defun
X
@defun num-natnump x
Returns true if @var{x} is numerically a nonnegative integer.
@end defun
X
@defun evenp x
Returns true if @var{x} is an even integer.
@end defun
X
@defun looks-evenp x
Returns true if @var{x} is an even integer, or a formula with a leading
multiplicative coefficient which is an even integer.
@end defun
X
@defun oddp x
Returns true if @var{x} is an odd integer.
@end defun
X
@defun provably-integerp x
Returns true if @var{x} is an integer, or a formula whose result
is guaranteed to be an integer (such as a call to @code{floor}).
@end defun
X
@defun ratp x
Returns true if @var{x} is a rational number, i.e., an integer or a
fraction.
@end defun
X
@defun realp x
Returns true if @var{x} is a real number, i.e., an integer, fraction,
or floating-point number.
@end defun
X
@defun provably-realp x
Returns true if @var{x} is a real number, or a formula whose result
is guaranteed to be real (such as a call to @code{abs}).
@end defun
X
@defun anglep x
Returns true if @var{x} is a real number or HMS form.
@end defun
X
@defun floatp x
Returns true if @var{x} is a float, or a complex number, error form,
interval, date form, or modulo form in which at least one component
is a float.
@end defun
X
@defun complexp x
Returns true if @var{x} is a rectangular or polar complex number
(but not a real number).
@end defun
X
@defun rect-complexp x
Returns true if @var{x} is a rectangular complex number.
@end defun
X
@defun polar-complexp x
Returns true if @var{x} is a polar complex number.
@end defun
X
@defun numberp x
Returns true if @var{x} is a real number or a complex number.
@end defun
X
@defun scalarp x
Returns true if @var{x} is a real or complex number or an HMS form.
@end defun
X
@defun vectorp x
Returns true if @var{x} is a vector (this simply checks if its argument
is a list whose first element is the symbol @code{vec}).
@end defun
X
@defun numvecp x
Returns true if @var{x} is a number or vector.
@end defun
X
@defun matrixp x
Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors,
all of the same size.
@end defun
X
@defun square-matrixp x
Returns true if @var{x} is a square matrix.
@end defun
X
@defun objectp x
Returns true if @var{x} is any numeric Calc object, including real and
complex numbers, HMS forms, date forms, error forms, intervals, and
modulo forms.  (Note that error forms and intervals may include formulas
as their components; see @code{constp} below.)
@end defun
X
@defun objvecp x
Returns true if @var{x} is an object or a vector.  This also accepts
incomplete objects, but it rejects variables and formulas (except as
mentioned above for @code{objectp}).
@end defun
X
@defun primp x
Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object,
i.e., one whose components cannot be regarded as sub-formulas.  This
includes variables, and all @code{objectp} types except error forms
and intervals.
@end defun
X
@defun constp x
Returns true if @var{x} is constant, i.e., a real or complex number,
HMS form, date form, or error form, interval, or vector all of whose
components are @code{constp}.
@end defun
X
@defun lessp x y
Returns true if @var{x} is numerically less than @var{y}.  Returns false
if @var{x} is greater than or equal to @var{y}, or if the order is
undefined or cannot be determined.  Generally speaking, this works
by checking whether @samp{@var{x} - @var{y}} is @code{negp}.  In
@code{defmath}, the expression @samp{(< x y)} will automatically be
converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=},
and @code{>=} are similarly converted in terms of @code{lessp}.@refill
@end defun
X
@defun beforep x y
Returns true if @var{x} comes before @var{y} in a canonical ordering
of Calc objects.  If @var{x} and @var{y} are both real numbers, this
will be the same as @code{lessp}.  But whereas @code{lessp} considers
other types of objects to be unordered, @code{beforep} puts any two
objects into a definite, consistent order.  One application of
@code{beforep} is that algebraic simplification rearranges the terms
in a product into canonical order, so that @samp{x y + y x} can
cheaply be simplified to @samp{2 x y}.
@end defun
X
@defun equal x y
This is the standard Lisp @code{equal} predicate; it returns true if
@var{x} and @var{y} are structurally identical.  This is the usual way
to compare numbers for equality, but note that @code{equal} will treat
0 and 0.0 as different.
@end defun
X
@defun math-equal x y
Returns true if @var{x} and @var{y} are numerically equal, either because
they are @code{equal}, or because their difference is @code{zerop}.  In
@code{defmath}, the expression @samp{(= x y)} will automatically be
converted to @samp{(math-equal x y)}.
@end defun
X
@defun equal-int x n
Returns true if @var{x} and @var{n} are numerically equal, where @var{n}
is a fixnum which is not a multiple of 10.  This will automatically be
used by @code{defmath} in place of the more general @code{math-equal}
whenever possible.@refill
@end defun
X
@defun nearly-equal x y
Returns true if @var{x} and @var{y}, as floating-point numbers, are
equal except possibly in the last decimal place.  For example,
314.159 and 314.166 are considered nearly equal if the current
precision is 6 (since they differ by 7 units), but not if the current
precision is 7 (since they differ by 70 units).  Most functions which
use series expansions use @code{with-extra-prec} to evaluate the
series with 2 extra digits of precision, then use @code{nearly-equal}
to decide when the series has converged; this guards against cumulative
error in the series evaluation without doing extra work which would be
lost when the result is rounded back down to the current precision.
In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}.
The @var{x} and @var{y} can be numbers of any kind, including complex.
@end defun
X
@defun nearly-zerop x y
Returns true if @var{x} is nearly zero, compared to @var{y}.  This
checks whether @var{x} plus @var{y} would by be @code{nearly-equal}
to @var{y} itself, to within the current precision, in other words,
if adding @var{x} to @var{y} would have a negligible effect on @var{y}
due to roundoff error.  @var{X} may be a real or complex number, but
@var{y} must be real.
@end defun
X
@defun is-true x
Return true if the formula @var{x} represents a true value in
Calc, not Lisp, terms.  It tests if @var{x} is a non-zero number.
@end defun
X
@defun reject-arg val pred
Abort the current function evaluation due to unacceptable argument values.
This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a
Lisp error which @code{normalize} will trap.  The net effect is that the
function call which led here will be left in symbolic form.@refill
@end defun
X
@defun inexact-value
If Symbolic Mode is enabled, this will signal an error that causes
@code{normalize} to leave the formula in symbolic form, with the message
``Inexact result.''  (This function has no effect when not in Symbolic Mode.)
Note that if your function calls @samp{(sin 5)} in Symbolic Mode, the
@code{sin} function will call @code{inexact-value}, which will cause your
function to be left unsimplified.  You may instead wish to call
@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic Mode will
return the formula @samp{sin(5)} to your function.@refill
@end defun
X
@node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals
@subsubsection Computational Functions
X
@noindent
The functions described here do the actual computational work of the
Calculator.  In addition to these, note that any function described in
the main body of this manual may be called from Lisp; for example, if
the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command,
this means @code{calc-sqrt} is an interactive stack-based square-root
command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt})
is the actual Lisp function for taking square roots.@refill
X
The functions @code{math-add}, @code{math-sub}, @code{math-mul},
@code{math-div}, @code{math-mod}, and @code{math-neg} are not included
in this list, since @code{defmath} allows you to write native Lisp
@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-},
respectively, instead.@refill
X
@defun normalize val
(Full form: @code{math-normalize}.)
Reduce the value @var{val} to standard form.  For example, if @var{val}
is a fixnum, it will be converted to a bignum if it is too large, and
if @var{val} is a bignum it will be normalized by clipping off trailing
(i.e., most-significant) zero digits and converting to a fixnum if it is
small.  All the various data types are similarly converted to their standard
forms.  Variables are left alone, but function calls are actually evaluated
in formulas.  For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will
return 6.@refill
X
If a function call fails, because the function is void or has the wrong
number of parameters, or because it returns @code{nil} or calls
@code{reject-arg} or @code{inexact-result}, @code{normalize} returns
the formula still in symbolic form.@refill
X
If the current Simplification Mode is ``none'' or ``numeric arguments
only,'' function calls may not be normalized.  However, the more
powerful simplification modes (like algebraic simplification) are
not handled by @code{normalize}.  They are handled by @code{calc-normalize},
which calls @code{normalize} and possibly some other routines, such
as @code{simplify} or @code{simplify-units}.  Programs should never
call @code{calc-normalize} except when popping or pushing values on
the stack.@refill
@end defun
X
@defun evaluate-expr expr
Replace all variables in @var{expr} that have values with their values,
then use @code{normalize} to simplify the result.  This is what happens
when you press the @kbd{=} key interactively.@refill
@end defun
X
@defmac with-extra-prec n body
Evaluate the Lisp forms in @var{body} with precision increased by @var{n}
digits.  This is a macro which expands to
X
@smallexample
(math-normalize
X  (let ((calc-internal-prec (+ calc-internal-prec @var{n})))
X    @var{body}))
@end smallexample
X
The surrounding call to @code{math-normalize} causes a floating-point
result to be rounded down to the original precision afterwards.  This
is important because some arithmetic operations assume a number's
mantissa contains no more digits than the current precision allows.
@end defmac
X
@defun make-frac n d
Build a fraction @samp{@var{n}:@var{d}}.  This is equivalent to calling
@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient.
@end defun
X
@defun make-float mant exp
Build a floating-point value out of @var{mant} and @var{exp}.
@end defun
X
@defun make-sdev x sigma
Build an error form out of @var{x} and the absolute value of @var{sigma}.
If @var{sigma} is zero, the result is the number @var{x} directly.
If @var{sigma} is negative or complex, its absolute value is used.
If @var{x} or @var{sigma} is not a valid type of object for use in
error forms, this calls @code{reject-arg}.
@end defun
X
@defun make-intv mask lo hi
Build an interval form out of @var{mask} (which is assumed to be an
integer from 0 to 3), and the limits @var{lo} and @var{hi}.  If
@var{lo} is greater than @var{hi}, an empty interval form is returned.
This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable.
@end defun
X
@defun sort-intv mask lo hi
Build an interval form, similar to @code{make-intv}, except that if
@var{lo} is less than @var{hi} they are simply exchanged, and the
bits of @var{mask} are swapped accordingly.
@end defun
X
@defun make-mod n m
Build a modulo form out of @var{n} and the modulus @var{m}.  Since modulo
forms do not allow formulas as their components, if @var{n} or @var{m}
is not a real number or HMS form the result will be a formula which
is a call to @code{makemod}, the algebraic version of this function.
@end defun
X
@defun float x
Convert @var{x} to floating-point form.  Integers and fractions are
converted to numerically equivalent floats; components of complex
numbers, vectors, HMS forms, date forms, error forms, intervals, and
modulo forms are recursively floated.  If the argument is a variable
or formula, this calls @code{reject-arg}.
@end defun
X
@defun compare x y
Compare the numbers @var{x} and @var{y}, and return @i{-1} if
@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})},
0 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is
undefined or cannot be determined.@refill
@end defun
X
@defun numdigs n
Return the number of digits of integer @var{n}, effectively
@samp{ceil(log10(@var{n}))}, but much more efficient.  Zero is
considered to have zero digits.
@end defun
X
@defun scale-int x n
Shift integer @var{x} left @var{n} digits, or right -@var{n} digits
with truncation toward zero.
@end defun
X
@defun scale-rounding x n
Like @code{scale-int}, except that a right shift rounds to the nearest
integer rather than truncating.
@end defun
X
@defun fixnum n
Return the integer @var{n} as a fixnum, i.e., a native Lisp integer.
If @var{n} is outside the permissible range for Lisp integers (usually
24 binary bits) the result is undefined.
@end defun
X
@defun sqr x
Compute the square of @var{x}; short for @samp{(^ @var{x} 2)}.
@end defun
X
@defun quotient x y
Divide integer @var{x} by integer @var{y}; return an integer quotient
and discard the remainder.  If @var{x} or @var{y} is negative, the
direction of rounding is undefined.
@end defun
X
@defun idiv x y
Perform an integer division; if @var{x} and @var{y} are both nonnegative
integers, this uses the @code{quotient} function, otherwise it computes
@samp{floor(@var{x}/@var{y})}.  Thus the result is well-defined but
slower than for @code{quotient}.
@end defun
X
@defun imod x y
Divide integer @var{x} by integer @var{y}; return the integer remainder
and discard the quotient.  Like @code{quotient}, this works only for
integer arguments and is not well-defined for negative arguments.
For a more well-defined result, use @samp{(% @var{x} @var{y})}.
@end defun
X
@defun idivmod x y
Divide integer @var{x} by integer @var{y}; return a cons cell whose
@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr}
is @samp{(imod @var{x} @var{y})}.@refill
@end defun
X
@defun pow x y
Compute @var{x} to the power @var{y}.  In @code{defmath}, this can also
be written @samp{(^ @var{x} @var{y})} or @samp{(expt @var{x} @var{y})}.
@end defun
X
@defun abs-approx x
Compute a fast approximation to the absolute value of @var{x}.  For
example, for a rectangular complex number the result is the sum of
the absolute values of the components.
@end defun
X
@findex two-pi
@findex pi-over-2
@findex pi-over-4
@findex pi-over-180
@findex sqrt-two-pi
@findex sqrt-e
@findex e
@findex ln-2
@findex ln-10
@defun pi
The function @samp{(pi)} computes @samp{pi} to the current precision.
Other related constant-generating functions are @code{two-pi},
@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi},
@code{e}, @code{sqrt-e}, @code{ln-2}, and @code{ln-10}.  Each function
returns a floating-point value in the current precision, and each uses
caching so that all calls after the first are essentially free.@refill
@end defun
X
@defmac math-defcache @var{func} @var{initial} @var{form}
This macro, usually used as a top-level call like @code{defun} or
@code{defvar}, defines a new cached constant analogous to @code{pi}, etc.
It defines a function @code{func} which returns the requested value;
if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})}
form which serves as an initial value for the cache.  If @var{func}
is called when the cache is empty or does not have enough digits to
satisfy the current precision, the Lisp expression @var{form} is evaluated
with the current precision increased by four, and the result minus its
two least significant digits is stored in the cache.  For example,
calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34
digits, rounds it down to 32 digits for future use, then rounds it
again to 30 digits for use in the present request.@refill
@end defmac
X
@findex half-circle
@findex quarter-circle
@defun full-circle symb
If the current angular mode is Degrees or HMS, this function returns the
integer 360.  In Radians mode, this function returns either the
corresponding value in radians to the current precision, or the formula
@samp{2*pi}, depending on the Symbolic Mode.  There are also similar
function @code{half-circle} and @code{quarter-circle}.
@end defun
X
@defun power-of-2 n
Compute two to the integer power @var{n}, as a (potentially very large)
integer.  Powers of two are cached, so only the first call for a
particular @var{n} is expensive.
@end defun
X
@defun integer-log2 n
Compute the base-2 logarithm of @var{n}, which must be an integer which
is a power of two.  If @var{n} is not a power of two, this function will
return @code{nil}.
@end defun
X
@defun div-mod a b m
Divide @var{a} by @var{b}, modulo @var{m}.  This returns @code{nil} if
there is no solution, or if any of the arguments are not integers.@refill
@end defun
X
@defun pow-mod a b m
Compute @var{a} to the power @var{b}, modulo @var{m}.  If @var{a},
@var{b}, and @var{m} are integers, this uses an especially efficient
algorithm.  Otherwise, it simply computes @samp{(% (^ a b) m)}.
@end defun
X
@defun isqrt n
Compute the integer square root of @var{n}.  This is the square root
of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}.
If @var{n} is itself an integer, the computation is especially efficient.
@end defun
X
@defun to-hms a ang
Convert the argument @var{a} into an HMS form.  If @var{ang} is specified,
it is the angular mode in which to interpret @var{a}, either @samp{'deg}
or @samp{'rad}.  Otherwise, the current angular mode is used.  If @var{a}
is already an HMS form it is returned as-is.
@end defun
X
@defun from-hms a ang
SHAR_EOF
true || echo 'restore of calc.texinfo failed'
fi
echo 'End of  part 53'
echo 'File calc.texinfo is continued in part 54'
echo 54 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].